Inside Macintosh: QuickTime
The Movie Toolbox allows you to define alternate tracks in a movie. You can use alternate tracks to support multiple languages or to present different levels of visual quality in the movie. You collect alternate tracks into groups. Alternate track groups are collections of tracks that conceptually represent some data but are appropriate for use in different play environments. For example, you might have some 4-bit data in one track and some 8-bit data in another. Working with alternate tracks allows you to set up alternatives from which the Movie Toolbox can choose.
The Movie Toolbox selects one track from each alternate group when it plays the movie. For example, you could create a movie that has three separate audio tracks: one in English, one in French, and one in Spanish. You would collect these audio tracks into an alternate group. When the user plays the movie, the Movie Toolbox selects the track from this group that corresponds to the current language setting for the movie.
Similarly, you can use alternate tracks to store data of different quality. When the user plays the movie, the Movie Toolbox selects the track that best suits the capabilities of the Macintosh computer on which the movie is being played. In this manner, you can create a single movie that can accommodate the playback characteristics of a number of different computer configurations.
The Movie Toolbox allows you to store quality information for media structures that are assigned to either sound or video tracks. For all tracks, the Movie Toolbox uses bits 6 and 7 of the quality setting. These bits encode a relative quality value. These values range from 0 to 3. You can use higher quality values to indicate larger sample sizes. For example, consider a movie that has two sound tracks that are alternates for each other--one contains 8-bit sound while the other contains 16-bit sound. You could assign a quality value of mediaQualityNormal to the 8-bit media and a value of mediaQualityBetter to the 16-bit media. The Movie Toolbox would only play the 16-bit media if the Macintosh configuration could handle 16-bit sound. Otherwise, the Movie Toolbox would use the 8-bit media. The sound media handler determines the sample size for each sound media for the Movie Toolbox by examining the media's sound description structure.
In addition, the Movie Toolbox also uses bits 0 through 5 (the low-order bits) of the quality setting. You use these bits to indicate the pixel depths at which the media should be played. Each bit corresponds to a single depth value, ranging from 1-bit pixels to 32-bit pixels. You may use these bits to control the playback of both video and sound tracks.
As an example, consider a movie that contains three video tracks with the following characteristics:
|
Compressed using the Joint Photographic Experts Group (JPEG) compressor |
You could assign the following quality values to these track's media structures:
The Movie Toolbox would always use Track A when playing the movie on 1-bit and 2-bit displays. At the other pixel depths, the video media handler determines which track to use by examining the availability and performance of the specified decompressors. If the JPEG decompressor can play back at full frame rate, the Movie Toolbox would use Track C. Otherwise, the Toolbox uses Track B. The video media handler determines the compressor that is appropriate for each media by examining the media's image description structure.
You set a movie's language by calling the SetMovieLanguage function.
To establish alternate groups of tracks, you can use the SetTrackAlternate and GetTrackAlternate functions.
You can work with the language and quality characteristics of media by calling the GetMediaLanguage , SetMediaLanguage , GetMediaQuality , and SetMediaQuality functions.
By default, the Movie Toolbox automatically selects the appropriate tracks to play according to a movie's quality and language settings, as well as the capabilities of the Macintosh computer. Whenever your application calls the SetMovieGWorld , SetMovieBox , UpdateMovie , or SetMovieMatrix function (described on SetMovieGWorld , SetMovieBox , UpdateMovie , and SetMovieMatrix , respectively), the Movie Toolbox checks each alternate group for an appropriate track. However, you can control this selection process. Use the SetAutoTrackAlternatesEnabled function to enable or disable automatic track selection. The SelectMovieAlternates function instructs the Movie Toolbox to select appropriate tracks immediately. If no tracks in an alternate track group are enabled, then the Movie Toolbox does not activate any track from that group during automatic track selection.
The SetMovieLanguage function allows your application to specify a movie's language. You specify the language by supplying the appropriate language or region code (see Inside Macintosh: Text for more information on language and region codes).
pascal void SetMovieLanguage (Movie theMovie, long language);
The SelectMovieAlternates function allows your application to instruct the Movie Toolbox to select appropriate tracks immediately.
pascal void SelectMovieAlternates (Movie theMovie);
You can call the SelectMovieAlternates function even if you have disabled automatic track selection with the SetAutoTrackAlternatesEnabled function (which is described in the next section) or by setting the newMovieDontAutoAlternate flag when you created the movie (see newMovieDontAutoAlternate for details on this flag).
The SetAutoTrackAlternatesEnabled function allows your application to enable and disable automatic track selection by the Movie Toolbox.
pascal void SetAutoTrackAlternatesEnabled (Movie theMovie,
Boolean enable);
If automatic track selection is enabled, the Movie Toolbox selects appropriate tracks whenever your application calls the SetMovieGWorld , SetMovieBox , UpdateMovie , or SetMovieMatrix functions (described on SetMovieGWorld , SetMovieBox , UpdateMovie , and SetMovieMatrix , respectively). When you enable automatic track selection, the Movie Toolbox immediately selects enabled tracks for the movie. This overrides the setting of the newMovieDontAutoAlternate flag (see newMovieDontAutoAlternate for details on this flag).
The SetTrackAlternate function allows your application to add tracks to or remove tracks from alternate groups.
pascal void SetTrackAlternate (Track theTrack, Track alternateT);
The GetTrackAlternate function allows your application to determine all the tracks in an alternate group. You specify the group by identifying a track in the group. The group list is circular, so you must specify a different track in the group each time you call this function.
pascal Track GetTrackAlternate (Track theTrack);
The GetTrackAlternate function returns the track identifier of the next track in the group. If the track you specify does not belong to a group, the function returns the same identifier you supply. Because the alternate group list is circular, you have retrieved all the tracks in the group when the function returns the track identifier that you supplied the first time you called the GetTrackAlternate function. If there is only one track in an alternate group, this function returns the track identifier you supply.
The SetMediaLanguage function sets a media's language or region code. You should call this function only when you are creating a new media. See Inside Macintosh: Text for more information on language and region codes.
pascal void SetMediaLanguage (Media theMedia, short language);
The GetMediaLanguage function returns a media's language or region code. See Inside Macintosh: Text for more information on language and region codes.
pascal short GetMediaLanguage (Media theMedia);
The SetMediaQuality function sets a media's quality level value. The Movie Toolbox uses this quality value to determine which track it selects to play on a given Macintosh computer. You should set this value only when you are creating a new media.
pascal void SetMediaQuality (Media theMedia, short quality);
The GetMediaQuality function returns a media's quality level value. The Movie Toolbox uses this quality value to influence which track it selects to play on a given Macintosh computer.
pascal short GetMediaQuality (Media theMedia);
The GetMediaQuality function returns the media's quality value. The quality value indicates the pixel depths at which the media can be played. This even applies to sound media. The low-order 6 bits of the quality value correspond to specific pixel depths. If a bit is set to 1, the media can be played at the corresponding depth. More than one of these bits may be set to 1. The following bits are defined:
In addition, bits 6 and 7 define the media's quality level. A value of 0 corresponds to the lowest quality level; a value of 3 corresponds to the highest quality level.